fix(driver-memory): analytics dateRange resolves on the UTC calendar, not the process-local one (#15825) - #16047

Fixes #15825

MemoryAnalyticsService.query() lowers a string dateRange through parseDateRangeString(), and that function built its window on the local calendar and rendered it as UTC. There were two independent defects, and each is repaired and pinned separately here.

Defect 1 — the window boundary was LOCAL midnight

new Date(y, m, d) constructs local midnight; toISOString() renders that instant in UTC. So in any process not sitting at UTC, the 'today' bucket was the local day expressed as a UTC range. ⛔ Wrong on every day of the year, with no DST transition needed. Reproduced before touching anything, clock at 2026-09-05T20:51Z, by transcribing the function verbatim from origin/main:

(The card predicted 08:00Z for Los Angeles; 07:00Z is the same defect in PDT rather than PST — both are pinned, 2026-09-05 and 2026-01-15.)

Defect 2 — the last N ... legs mixed two calendars

setDate(getDate() - n) is local arithmetic and toISOString() is a UTC rendering. setDate preserves wall-clock time, so the instant moves n × 24h only while every local day in the window is 24 hours long; across a DST transition it moves 23h or 25h and the window start slips an hour. setMonth / setFullYear are the same class — and can move the answer by a whole day: at America/New_York with the clock at 2026-01-01T12:00Z, last 1 month started at 2025-12-02T00:00Z instead of 2025-12-01T00:00Z.

⭐ The two are independent — demonstrated, not asserted

⛔ setDate → setUTCDate does not fix defect 1, and Date.UTC alone does not fix defect 2. Each half was ablated on its own, in one shell, with the mutation proven on disk by anchored grep counts before measuring and the restore proven afterwards (blob hash == HEAD blob and git diff HEAD empty):

That green cell is the whole point: the boundary pin is insensitive to defect 2, so the two defects are separable and each pin measures its own.

The mutated file is imported by both pins as a same-package relative specifier (./memory-analytics.js), and this package's vitest.config.ts aliases only @objectstack/* → source, so the ablation reaches source; no dist rebuild sits in its path and the "unbuilt ablation stays green" failure mode does not apply. Both ablation legs carried a trap … EXIT INT TERM with absolute paths — and it earned its keep: a first run died on a shell bug mid-mutation, and the trap left the tree byte-exact (verified by hash).

Why UTC, and not "any consistent calendar"

The rest of the platform resolves a bare date to the UTC day: @objectstack/core's {today} filter-token macro builds its reference day as new Date(Date.UTC(year, month - 1, day)) and falls back to UTC parts when the context carries no timezone, and {TODAY()} in flow templates resolves to the UTC day (#14852 repaired the identical two-calendar shape there — its template-date-offset-dst.test.ts is on origin/main and was used as the model for the DST pin's structure). UTC is also the terminal fallback of the engine's own resolution chain, selection.timezone ?? context.timezone ?? 'UTC' (ADR-0053 Phase 2). Before this change the same analytics question asked through this path and through a flow token could select different rows in one deployment — restoring that agreement, not the hour count, is what earns the p2.

Scope — spelling fix only

⛔ The parser is not replaced, per triage's ruling on the card: 「先做拼写修复（UTC 化两个缺陷），⛔ 不要顺手换掉整个 parser」. Its vocabulary, its [range, range] fallback and the shape of the emitted $match are untouched. Triage asked that anyone proposing a replacement first measure which range forms actually reach it — that measurement was taken and filed rather than acted on:

• driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041 — an unparseable dateRange is silently accepted and matches every row (measured through mingo), and the schema's own documented spelling 'Last 7 days' is one of the unrecognised forms (startsWith('last ') is case-sensitive).
• driver-memory analytics resolves a string dateRange without ever reading the declared AnalyticsQuery.timezone #16042 — this path never reads the declared AnalyticsQuery.timezone; UTC-ising is correct for every query that carries none, but the supplied-timezone case is left exactly as found.

Neither is repaired here. Sibling card #15824 (HistoryCleanupManager) is the same class in a different file and was ⛔ not absorbed.

Clause-② — measured no

Built at head → swapped only the changed source back to origin/main (2024eca4f) → rebuilt → diffed the built dist/index.d.ts → restored byte-exact and proved it (worktree and index):

dist/index.d.ts sha (head): 09684929832de0380c056b073ccef8a195fe8b0a
dist/index.d.ts sha (base): 09684929832de0380c056b073ccef8a195fe8b0a   -> IDENTICAL, 50852 bytes both

No exported symbol or signature moves. Separately on the other half of the test — no request is newly accepted or rejected: parseDateRangeString is a private method, it enters the same two branches on exactly the same inputs, the fallback is untouched, and AnalyticsQuerySchema is unchanged. What moved is the answer, not the surface. Bump is nevertheless minor, matching how this package levels an answer-changing analytics repair — the act over the commit type.

Verification

Gate union re-derived after the final commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (provenance line checked: derived from this repo's tree) and run at cb1cb6e54, the head of this branch:

• 53 of 53 gate families green. 51 on the first pass; check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3 — the gates' own text says this is ⛔ not a pass and ⛔ not a finding), so the workspace closure was built (turbo run build, 71/71 successful) and both then ran green: ✓ check:dual-build-cjs-loads — 103 published require entry point(s) across 66 package(s) load and check-type-check-coverage --re-measure: OK — 12 ledger entr(ies) re-measured in 106.7s, 140 raw tsc error(s) total, none above its recorded number.
• pnpm --filter @objectstack/driver-memory test — 43 files, 1096 tests, all pass.
• pnpm --filter @objectstack/driver-memory typecheck — exit 0. --listFiles confirms both new pins are inside the tsc program (include: src/**/*, no *.test.ts exclusion), so that green is a reading about them and not a vacuous pass.
• pnpm lint (eslint . --no-inline-config, whole repo) — exit 0, no findings. Run in full rather than narrowed.

Every exit code above was captured before any pipe, and each gate's own verdict line is quoted rather than a bare $?.

Notes for review

• ⛔ A DST regression test that runs only at TZ=UTC asserts nothing — the two spellings are indistinguishable there. Both pin files therefore fake the zone and the instant, and each carries an inline control that evaluates the old spelling and asserts it disagrees, so a green run cannot be confused with "these cells stopped being live".
• The 13 DST cells were measured, not guessed — taken from a 9-zone × 366-day × 4-unit sweep of 2026. Both hemispheres, both transition directions, all four legs, and two zones whose offset is not a whole hour (America/St_Johns −03:30, Pacific/Chatham +12:45).
• The DST pin's oracle is timezone-invariance (the TZ=UTC run is the reference answer, since both spellings coincide there) rather than a re-derived expected value — for month / year there is no offset-free definition, and re-deriving one would just be the fix written twice. Where a definition does exist (day / week) it is asserted as well.

🤖 Generated with Claude Code

Generated by Claude Code

Generated by Claude Code